•Compatible with Metrowerks CW7 and Symatec C 8--see Changes.
•Surprising timing results for PCI Macs--see Video synch.
•Update on our request to Apple for support of high frame rates--see Video synch.
•I recommend the PowerMac 7500 (best specs) or 7200 (best buy) over other models to anyone that wants to buy a mac to show movies (i.e. copy images to the screen in real time)--see Video synch.
•Raster graphics bibliography.doc, written by David Brainard, in Notes folder.
The VideoToolbox is a collection of two hundred C subroutines and several demo and utility programs that I and others have written to do visual psychophysics with Macintosh computers. It is fully compatible with 680x0 and PowerPC Macs and with Metrowerks CodeWarrior 7 and Symantec C compilers. It's free and may not be sold without permission. It should be useful to anyone who wants to present accurately specified visual stimuli or use the Mac for psychometric experiments. The text file "Video synch" discusses all the ways of synchronizing programs to video displays and the many pitfalls to avoid. The TimeVideo application checks out the timing of all video devices in anticipation of their use in critical real-time applications, e.g. movies or lookup table animation. "Video bugs" reports all known bugs uncovered by TimeVideo's testing of 56 video cards and drivers. Low-level routines control video timing and lookup tables, display real-time movies, and implement the luminance-control algorithms suggested by Pelli and Zhang (1991). In particular, CopyWindows (or CopyBitsQuickly) faithfully copies between on-screen and off-screen windows (or bit/pixmaps), WindowToEPS saves an image to disk as encapsulated PostScript, for later printing or incorporation into a document, and SetEntriesQuickly and GDSetEntries load the screen's color lookup table, all without any of QuickDraw's color translations. NoisePdfFill.c quickly generates visual noise images whose pixels are samples from a specified probability density function. High-level routines help analyze psychophysical experiments (e.g. maximum-likelihood fitting and graphing of psychometric data). Assign.c is a runtime C interpreter for C assignment statements, which is useful for controlling experiments and sharing calibration data. This collection has been continually updated since 1991. More that one hundred colleagues subscribe to the email distribution (see below), and have indicated that they are using the software in their labs. Documentation is in the source files themselves. Many of the routines are Mac-specific, but some very useful routines, e.g. the luminance-control, statistics, maximum-likelihood fitting algorithms, and the runtime interpreter are written in Standard C and will work on any computer. Those wishing to acknowledge use of the VideoToolbox software might cite:
Pelli, D. G. and Zhang, L. (1991) Accurate control of contrast on microcomputer displays. Vision Research, 31, 1337-1350. Reprints are available.
AVAILABILITY:
The VideoToolbox software is updated several times a year. You can download the latest version from any of the archives below. To get future versions automatically, just send me your name and email address. Each time I post a new version of the VideoToolbox to the Info-Mac Archive, I email a copy to everyone on the subscription list; there are currently 173 subscribers. (Let me know if you prefer notification only, without the 3 MB enclosure.)
CompuServe://MacDev forum/Library 4 C and Pascal/VIDEOT.SEA
(The filename changes slightly to reflect each version's release date. You can request a file from the Info-Mac Archive by email; for instructions send a query to Info-Mac-Request@sumex-aim.stanford.edu.)
The VideoToolbox is distributed as a Stuffit archive. You'll need Stuffit Expander to unpack it.
Microsoft Windows users can now use StuffIt Expander too
ftp://ftp.aladdinsys.com/Pub/SITEX10.UUE
ftp://ftp.aladdinsys.com/Pub/SITEX10.EXE
[The ISR Video Attenuator is a commercial product; contact Art_Wixson@isr.syr.edu. Ordering instructions are in the "Video attenuator" document. I have no financial involvement in the ISR Video Attenuator.]
AUTHORS:
Adobe (ATMInterface.c and ATMInterface.h)
Apple (IsCmdPeriod.c,MoveMouse.c,TrapAvailable.c, Zoom.c)
Kevin Bell (PatchExitToShell in Timer.c)
Philipp Biermann ("Multisync Sense Pins.note")
David Brainard (AfterDark.c,12 in Assign.c,1 in GDOpenWindow.c, GetTimeDateString.c, PeekTimer in Timer.c)
EJ Chichilniski (SetFileInfo.c)
Raynald Comtois (SetEntriesQuickly.c)
Frans Cornelissen (VideoToolbox folder icon)
Steve Coy (PatchExitToShell in Timer.c)
Bart Farell (several routines in SetOnePixel.c and SetPixelsQuickly.c)
Bill Haake (SetEntriesQuickly.c)
C.K. Haun, Apple Computer (KillEveryoneButMe.c)
Bill Hofmann (PatchExitToShell in Timer.c)
Mike Kahl (CopyQuickDrawGlobals.c, kbhit.c)
Joseph Laffey (GetVersionString.c)
Peter Lennie (SetEntriesQuickly.c)
J.N. Little & jmb (ReadMATLABFile.c)
Jamie R. McCarthy (IsCmdPeriod.c)
Izumi Ozhawa (CVNetConvert in the Utilities folder)
Denis Pelli (most of the routines)
Dave Radcliffe (FlushCacheRange.c)
Evan Relkin (kbhit.c)
Mike Schechter (PixMapToPICT.c)
SPLAsh Resources (HideMenuBar.c, SetMouse.c)
Preeti Verghese (GetVoltage.c)
Detailed attribution appears in each file. Please advise of any errors or omissions.
C COMPILERS:
If you don't have a compiler, I'd suggest buying Metrowerks CodeWarrior C Gold ($99 academic price). All the VideoToolbox demos now compile and run as native code on both 68k and Power PC Macs. You can use Symantec C, but I prefer CodeWarrior. See the VideoToolbox "Advice" document for comments and ordering information.
COMPUTERS OTHER THAN MACS:
Microsoft Windows users can use SITEX10.EXE to unstuff the VideoToolbox archive. Markus Schaumberger, markus.schaumberger@lrz.uni-muenchen.de, says, "Just drag & drop the icon of the archive onto the program window. Everything else is done by the program itself. There are only two problems:
1. .TXT files are not translated, so Mac special characters appear as arbitrary graphic signs, and carriage returns (Mac standard) are not translated to carriage return plus linefeed (DOS standard).
2. DOS filenames may only consist of 8 characters for the name and 3 for the extension. So the long filenames included in the video-toolbox are truncated. If the truncated name isn't unique the Stuffit program (SITEX10) does only use 7 characters and adds a number, so that no file is overwritten. Using the Contents doc, it's no problem to identify them."
StuffIt Expander for Microsoft Windows
ftp://ftp.aladdinsys.com/pub/SITEX10.UUE
ftp://ftp.aladdinsys.com/pub/SITEX10.EXE
MATLAB:
David Brainard (brainard@condor.psych.ucsb.edu) has published interface files that make it easy to use the VideoToolbox from within MATLAB.
Andrew B. Watson and Joshua Solomon, beau@vision.arc.nasa.gov and jsolomon@vision.arc.nasa.gov, "have created a Mathematica package, Cinematica, containing functions ... for producing calibrated grayscale movies on a Macintosh
from within the Mathematica programming environment. It makes use of
the ISR Video Attenuator and Video Toolbox software library."
You'll need to pre-compile the header: see VideoToolbox.pch (for CodeWarrior) or VideoToolbox.c (for THINK C). If you get link errors when rebuilding your re-existing project, it is likely that you'll need to add CenterRectInRect.c and MacMemory.c to your project.
GETTING STARTED:
Try the demos: Sandstorm, Grating, FlickeringGrating, Filter, and TimeVideo. TimeVideo times all of your displays, telling you how quickly you can show movies and do lookup table animation. Read "Video synch" and "Advice".
The VideoToolbox applications--mostly demos--now come in four possible flavors, indicated by the extension to the file name, e.g. Sandstorm, Sandstorm.68k, Sandstorm.ppc, or Sandstorm.fat. The plain extension indicates a 68k application produced by THINK C; it should run fine on all Macs, by virtue of the 68k emulator on the PowerPC. (However, many Macs lack the 68881 floating point unit, "fpu", and the 68k emulator on the PowerPC doesn't include fpu emulation. Applications compiled to use an fpu will fail on these computers unless you install something like SoftwareFPU. See the "Advice" document.) The ".68k" extension indicates a 68k application produced by Metrowerks CodeWarrior C; it too should run on all Macs. The ".ppc" extension indicates a PowerPC application produced by Metrowerks CodeWarrior C; it will only run on PowerPC Macs. The ".fat" extension indicates a "fat binary" 68k/PowerPC application produced by Metrowerks CodeWarrior C; it will run native on all Macs. (As you may infer from the file sizes, a fat binary file is essentially the combination of the two native applications, plus a cfg resource that says what's where. Most of the "ppc" projects in the VideoToolbox collection have been configured to produce a fat application.) Bear in mind, when using the demos, that I never use them, so they're much less polished than the files in the VideoToolboxSources folder, which we use every day.
You'll want the VideoToolboxSources folder to be included in your project's search path. Don't copy VideoToolbox source files to your project's folder (dealing with updates to the VideoToolbox would become a nightmare); instead just "Add" the files to your project by using your compiler's Source or Project menu. That will make it easy to update the VideoToolbox. In Metrowerks, add the VideoToolboxSources folder to each of your projects' "Access paths" preferences. For THINK C, place an alias to the VideoToolboxSources folder inside the THINK C Aliases folder.
When compiling for 68k there is a bewildering variety of options about size of int and double, and whether to use 68881 fpu instructions. I usually opt for 4-byte int, 10-byte double, and fpu instructions. You can choose whatever you want, but you must be consistent across all components of your project, i.e. the pre-compiled header (chosen by name), the compiler settings (use Edit:Preferences:Processor), and the libraries (chosen by name). It's a good idea to call the VideoToolbox routine Require.c near the beginning of your program, as it does some sanity checks to make sure your choices of pre-compiled header, compiler settings, and ANSI library are consistent.
Follow the instructions in VideoToolbox.pch (CodeWarrior) or VideoToolbox.c (THINK C) to precompile VideoToolbox.h to recreate the precompiled header or headers that you'll need, since they must be produced by your version of the compiler. (If you're producing an external code resource for MATLAB then use VideoToolboxMATLAB.c instead.) Put all the pre-compiled headers in "VideoToolbox:VideoToolboxSources:Precompiled headers". VideoToolbox.pch, in CodeWarrior, will automatically generate the correct file name. Here's the naming convention that I use:
"VideoToolbox.f.pre" = THINK C, 68k, 2-byte int, "universal" floating format with 8881 fpu.
"VideoToolbox.pre" = THINK C, 68k, 2-byte int, "universal" floating format without fpu.
"VideoToolbox.68k.4i.f.pre" = CodeWarrior, 68k, 4-byte int, 12-byte double for 8881.
"VideoToolbox.68k.4i.pre" = CodeWarrior, 68k, 4-byte int, 10-byte double for no fpu.
"VideoToolbox.ppc.pre" = CodeWarrior, PowerPC, necessarily 4-byte int and 8-byte double.
Require.c: All the compilers consider it the user's responsibility (why?) to ensure that the current compiler settings are consistent with those of the object code libraries (e.g. "ANSI" in THINK C or "ANSI (4i/f) C.68k" in CodeWarrior) and the pre-compiled header. It is very easy to forget this rule, leading to mysterious crashes. (CodeWarrior checks for consistency of the pre-compiled header, but still doesn't check the libraries.) Therefore it is highly recommended that you call the VideoToolbox Require() once at the beginning of your program because it explicitly checks for the compatibility of the assumed size of int and double among the three components, producing a helpful error message instead of a mysterious crash if you goof.
The VideoToolbox contains up-to-date project documents for current versions of the compilers (names ending in ".µ" for Metrowerks CodeWarrior and ".π" for THINK C). Users of older versions of the compilers (e.g. THINK C 6 or CW6) unfortunately can't use the new projects: complain to the authors of the compilers, who seem to have no compunction about changing the project format every time they release a new version. I suggest you upgrade to the current version; see "Advice".
All the programs that do accurate luminance control use the monitor-calibration data stored in LuminanceRecord1.h (the number is a screen number, similar--but not identical--to the number that appears in the Monitors control panel). These calibration files describe one of my monitors (an Apple High-Resolution Monochrome), and, naturally, before doing any serious data collection you should create new files that describe your own monitors. Use the CalibrateLuminance program and a photometer.
DON'T BOTHER WITH PIXMAPS, JUST USE WINDOWS AND GWORLDS: and use CopyWindows instead of CopyBits or CopyBitsQuickly. CopyBits is one of Apple's more impressive routines. It's powerful and fast. For my purposes its only drawback is that I haven't always been able to prevent it from doing color translations. So I wrote CopyBitsQuickly to copy images without color translations. (A long time ago CopyBits used to be slow, but that's history. At present CopyBitsQuickly is approximately the same speed as CopyBits, except when doing image expansion, for which it is much faster than CopyBits.) However, both CopyBits and CopyBitsQuickly require you to supply pixmap pointers, which can be a nuisance. These days, our programs use windows (created by GDOpenWindow or NewCWindow) and GWorlds (which are really offscreen windows, created by NewGWorld). Extracting the pixmap's pointer from the guts of the window is straightforward but messy (see BitMapPtr in GDOpenWindow.c). Now you don't have to bother. Just call CopyWindows.c. Its first two arguments are the source and destination windows. The rest of the arguments are like those for CopyBits or CopyBitsQuickly. It makes your programs much easier to write and read, and probably makes them more robust because there are a lot of subtle and fragile assumptions that people often make in calling CopyBits, which CopyWindows takes care of for you. Look at the demo NoiseVBL.c.
NUMERICAL RECIPES IN C:
A few programs in the VideoToolbox (CalibrateLuminance.c, DrawGrating.c, PsychometricFit.c, and Quick3) use the (very handy) Numerical Recipes software and book. Required changes to these routines are described in the "Improve Numerical Recipes" document in the Notes folder. I have included pre-compiled CalibrateLuminance and Quick3 applications for users that don't have the Numerical Recipes. The Numerical Recipes C Set for Macintosh (main book, example book, and disk) costs $90 from:
Cambridge University Press
Orders Department
110 Midland Avenue
Port Chester, NY 10573
1-(800)-227-0247
<SANE.h> IS DEAD. LONG LIVE <fp.h>:
In going to the PowerPC, Apple wisely decided to drop <SANE.h>, i.e. their Standard Apple Numerics Environment routines, in favor of <fp.h>, i.e. the Floating-Point C Extensions (FPCE) proposed by the Numerical C Extensions Group (NCEG). SANE was uselessly slow anyway since it was tied to 10-byte doubles, whereas the 68881 floating point chip used 12-byte doubles. The <fp.h> extensions are very welcome, providing some handy math functions and providing standard ways of producing and testing for NAN and INF. <fp.h> provides standard routines very similar to the VideoToolbox routines IsNan and IsFinite. I would suggest favoring the fp.h routines since they are becoming standard. If you have any programs that use <SANE.h>, you should think about using <fp.h> instead. Note that VideoToolbox.h now automatically includes fp.h, if available, and otherwise includes math.h.
PORTABILITY:
Various issues to do with porting programs among different computers and compilers are discussed in the "Portability" document.
BUGS & SUGGESTIONS:
It's unlikely that you'll find any bugs, but if you do, please send me email so we can fix 'em. Suggestions and code donations (i.e. C routines to be included in the VideoToolbox, possibly in modified form, with full attribution) are warmly appreciated. Also many people have contributed useful paragraphs, which appear in the VideoToolbox notes, with attribution, about specific technical issues that they identified and perhaps solved.
denis@xp.psych.nyu.edu
NOT MULTIFINDER FRIENDLY:
Walt Makous writes, "I ran Sandstorm by clicking on the icon for the application, interrupted it by clicking outside the window, and then resumed it by clicking on the window again. This locks the keyboard so that the only way I can get back control is by using the programmer's switch." REPLY: Alas, I've never had any need to write polite applications that gracefully share the computer with other applications. Experiments always seem to deserve hogging it all. The Sandstorm demo allows you to invoke other applications, because it doesn't obscure the whole window, but it doesn't act like a good citizen in paying attention to the messages it gets from the Finder about what happened. (I would go ahead and make the demos multifinder-friendly if I knew how, but it hasn't seemed worth learning just for the sake of the demos.)
BLOCKMOVEDATA:
BlockMoveData is a new (as of System Update 3.0 to System 7.1) variant of BlockMove that omits cache flushing. Calling BlockMoveData() on earlier versions of the operating system will invoke plain old BlockMove(). BlockMove is coded in each computer's ROM to implement the fastest possible move. E.g. it uses the MOVE16 instruction on the 68040 processor. It may be faster than the generic code that most C compilers produce. When the Quadra's were released, Apple added code to the BlockMove trap to flush the instruction cache each time BlockMove was called, just in case the move was copying instructions that were in the cache. However, flushing the cache everytime you call BlockMove sacrifices the speed benefit of the cache, making it less advantageous to call BlockMove. In System Update 3.0 Apple finally gave developers a way of telling BlockMove not to flush the cache. You call BlockMoveData instead. However, if run on computers lacking System Update 3.0 the flag bit distinguishing BlockMoveData from the old BlockMove will be ignored and the cache will be flushed, which will slow you down. BlockMoveData() is defined in Apple's Memory.h in Apple's new Universal Header files, but is not defined in pre-Universal header files. VideoToolbox.h tests for that case and, if necessary, defines BlockMoveData, so that you may use it freely.
68040:
Peter Lennie writes (6/23/93): "On the latest developers CD [June? '93] there's a note about the Quadra's use of a trap to emulate the FINTRZ instruction, which isn't built into the 68040. This instruction is called commonly in the code generated by THINK C [5, when FPU use is enabled], and for me it became an issue in the loops that recalculate lookup tables during chromatic flicker. By rewriting the loop to avoid that instruction (using a small function supplied on the CD) I reduced the time it took to recalculate --as opposed to write-- the tables from 16msec to 1.6 msec." [Does anyone know whether this concern is still applicable to the current version? I don't use the Quadra. dgp]
DISCLAIMER (included at the request of the MacPsych archive):
The VideoToolbox is provided "as is" without warranty of any kind. Denis Pelli, New York University, SCiP, the operators of MacPsych, and St. Olaf College make no claims concerning the accuracy or correctness of the computer code contained in, or the results of the use of VideoToolbox. The entire risk as to the results and performance of VideoToolbox is assumed by you. If the VideoToolbox is defective you, and not Denis Pelli, New York University, SCiP, the operators of MacPsych, or St. Olaf College assume the entire cost of all necessary servicing, repair or correction.
